znp_interface.h File Reference

public methods for znp_interface.c More...

#include "znp_commands.h"

Defines

#define ZNP_MESSAGE_COMMAND_ID()   (CONVERT_TO_INT(znpBuf[SRSP_CMD_LSB_FIELD], znpBuf[SRSP_CMD_MSB_FIELD]))
#define COORDINATOR   0x00
#define ROUTER   0x01
#define END_DEVICE   0x02
#define DIP_STATE   0x00
#define DIP_MAC_ADDRESS   0x01
#define DIP_SHORT_ADDRESS   0x02
#define DIP_PARENT_SHORT_ADDRESS   0x03
#define DIP_PARENT_MAC_ADDRESS   0x04
#define DIP_CHANNEL   0x05
#define DIP_PANID   0x06
#define DIP_EXTENDED_PANID   0x07
#define MAX_DEVICE_INFORMATION_PROPERTY   0x07
#define DIP_MAC_ADDRESS_LENGTH   8
#define DIP_SHORT_ADDRESS_LENGTH   2
#define DIP_PARENT_SHORT_ADDRESS_LENGTH   2
#define DIP_PARENT_MAC_ADDRESS_LENGTH   8
#define DIP_CHANNEL_LENGTH   1
#define DIP_PANID_LENGTH   2
#define DIP_EXTENDED_PANID_LENGTH   8
#define ZB_WRITE_CONFIGURATION_LEN   2
#define SRSP_DIP_VALUE_FIELD   (SRSP_HEADER_SIZE+1)
#define ZCD_NV_STARTUP_OPTION   0x03
#define ZCD_NV_STARTUP_OPTION_LEN   1
#define ZCD_NV_LOGICAL_TYPE   0x87
#define ZCD_NV_LOGICAL_TYPE_LEN   1
#define ZCD_NV_ZDO_DIRECT_CB   0x8F
#define ZCD_NV_ZDO_DIRECT_CB_LEN   1
#define ZCD_NV_POLL_RATE   0x25
#define ZCD_NV_POLL_RATE_LEN   2
#define ZCD_NV_PRECFGKEY   0x62
#define ZCD_NV_PRECFGKEY_LEN   16
#define ZCD_NV_PRECFGKEYS_ENABLE   0x63
#define ZCD_NV_PRECFGKEYS_ENABLE_LEN   1
#define ZCD_NV_SECURITY_MODE   0x64
#define ZCD_NV_SECURITY_MODE_LEN   1
#define ZCD_NV_PANID   0x83
#define ZCD_NV_PANID_LEN   2
#define ZCD_NV_CHANLIST   0x84
#define ZCD_NV_CHANLIST_LEN   4
#define STARTOPT_CLEAR_CONFIG   0x01
#define STARTOPT_CLEAR_STATE   0x02
#define STARTOPT_AUTO   0x04
#define MAC_ACK   0x00
#define AF_APS_ACK   0x10
#define SAPI_APS_ACK   0x01
#define DEFAULT_RADIUS   0x0F
#define MAXIMUM_PAYLOAD_LENGTH   66
#define ALL_DEVICES   0xFFFF
#define ALL_ROUTERS_AND_COORDINATORS   0xFFFC
#define SECURITY_MODE_OFF   0
#define SECURITY_MODE_PRECONFIGURED_KEYS   1
#define SECURITY_MODE_COORD_DIST_KEYS   2
#define CALLBACKS_DISABLED   0
#define CALLBACKS_ENABLED   1
#define NO_TIMEOUT   0xFF
#define ANY_PAN   0xFFFF
#define DEV_HOLD   0
#define DEV_INIT   1
#define DEV_NWK_DISC   2
#define DEV_NWK_JOINING   3
#define DEV_NWK_REJOIN   4
#define DEV_END_DEVICE_UNAUTH   5
#define DEV_END_DEVICE   6
#define DEV_ROUTER   7
#define DEV_COORD_STARTING   8
#define DEV_ZB_COORD   9
#define DEV_NWK_ORPHAN   10
#define ANY_CHANNEL   0x07FFF800
#define MIN_CHANNEL   0x00000800
#define MAX_CHANNEL   ANY_CHANNEL
#define GPIO_SET_DIRECTION   0x00
#define GPIO_SET_INPUT_MODE   0x01
#define GPIO_SET   0x02
#define GPIO_CLEAR   0x03
#define GPIO_TOGGLE   0x04
#define GPIO_READ   0x05
#define ALL_GPIO_PINS   0x0F
#define GPIO_INPUT_MODE_ALL_PULL_DOWNS   0xF0
#define GPIO_INPUT_MODE_ALL_PULL_UPS   0x00
#define GPIO_INPUT_MODE_ALL_TRI_STATE   0x0F
#define GPIO_DIRECTION_ALL_INPUTS   0x00
#define MIN_NV_ITEM   1
#define MAX_NV_ITEM   6
#define NV_ITEM_1   0x0F01
#define NV_ITEM_2   0x0F02
#define NV_ITEM_3   0x0F03
#define NV_ITEM_4   0x0F04
#define NV_ITEM_5   0x0F05
#define NV_ITEM_6   0x0F06

Functions

unsigned char * znpInit ()
unsigned char * znpReset ()
char * getResetReason (unsigned char reason)
unsigned char * getVersion ()
unsigned int getRandom ()
void printZnpBuf ()
signed int waitForMessage (unsigned int messageType, unsigned char timeoutSecs)
void setZigbeeDeviceType (unsigned char deviceType)
void setPanId (unsigned int panId)
void setChannel (unsigned long channelMask)
void setStartupOptions (unsigned char option)
void setCallbacks (unsigned char cb)
void setPollRate (unsigned int pollRate)
void setSecurityMode (unsigned char securityMode)
void setSecurityKey (unsigned char *key)
unsigned char * getConfigurationParameter (unsigned char configId)
void getNetworkConfigurationParameters ()
unsigned char * getDeviceInformationProperty (unsigned char dip)
unsigned char * getMacAddress ()
unsigned char getDeviceState ()
char * getDeviceStateName (unsigned char state)
void getDeviceInformation ()
unsigned char getNvItemSize (unsigned char nvItem)
void writeNvItem (unsigned char nvItem, unsigned char *data)
unsigned char * readNvItem (unsigned char nvItem)
unsigned char sysGpio (unsigned char operation, unsigned char value)

Detailed Description

public methods for znp_interface.c

Rev
619
Author
dsmith
Date
2010-07-02 10:54:13 -0700 (Fri, 02 Jul 2010)

YOU ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.

Function Documentation

unsigned char* getConfigurationParameter ( unsigned char  configId  ) 

Retrieves the given configuration parameter from the ZNP.

Parameters:
configId the configuration parameter to retrieve. See Interface Spec for list of valid config parameters. Not checked for validity.
Returns:
pointer to beginning of configuration parameter
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Note:
does not verify configId is a valid configId
does not verify length returned in the SRSP matches what the length should be for that configId.
void getDeviceInformation (  ) 

Displays the radio's device Information Properties. Device Information Properties include:

  • Device State indicates whether the ZNP is on a network or not, and what type of device it is. This is a handy thing to check if things aren't operating correctly. If the device is starting as a coordinator, you'll see states of 01, 08, 08, then 09 once it has fully started.
  • MAC Address (aka IEEE Address) is a globally unique serial number for this IC.
  • Device Short Address is a network address assigned by the coordinator, similar to an IP Address in DHCP. The Coordinator always has a Short Address of 0.
  • Parent MAC Address is the IEEE Address of this device's "parent", i.e. which device was used to join the network. For a router, once joined this parent MAC address is irrelevant. This DIP will NOT be updated if the network reforms. For an end-device then this parent MAC address will always specify which router the end-device is joined to.
  • Channel is which frequency channel the device is operating on.
  • PAN ID (Personal Area Network Identifier) of the network is a unique number shared for all devices on the same network.
  • Extended PAN ID of the network is the coordinator's MAC Address.

If device is not connected to a network then the Short Address fields will be 0xFEFF, the Parent MAC Address and channel will be 0, and the Extended PAN ID will be this device's MAC Address.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
unsigned char* getDeviceInformationProperty ( unsigned char  dip  ) 

Retrieves the specified Device Information Property (DIP) from the ZNP.

Parameters:
dip the device information property to retrieve
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the DIP payload, or a pointer to indeterminate data if error.
unsigned char getDeviceState (  ) 

Retrieves the device state - indicates whether it is on the network or not.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
the device state: DEV_HOLD, DEV_NWK_DISC, DEV_ROUTER etc. or an indeterminate value if error.
char* getDeviceStateName ( unsigned char  state  ) 

Retrieves the name of the device state in a human-readable format. From API Specification.

Parameters:
state the value for the ZDO state
Returns:
the name of the ZDO state
unsigned char* getMacAddress (  ) 

Retrieves the Media Access Controller (MAC) Address (aka Long Address, aka IEEE Address) The MAC Address is an eight byte globally unique serial number for this IC.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the MAC address (LSB first), or a pointer to indeterminate data if error.
void getNetworkConfigurationParameters (  ) 

Utility method to display stored network configuration parameters. These are the configuration parameters stored in NV memory and are used to initialize the ZNP.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
unsigned char getNvItemSize ( unsigned char  nvItem  ) 

Retrieves the size of the selected Non-Volatile (NV) memory item. NV Items 1 through 4 are 2 bytes each; 5 & 6 are 16 bytes each.

Parameters:
nvItem which Non-Volatile memory item. Must be 1-6 inclusive.
Returns:
size of the given nvItem
unsigned int getRandom (  ) 

Retrieves a random number from the ZNP using SYS_RANDOM command.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
the random number, or indeterminate data if error.
char* getResetReason ( unsigned char  reason  ) 

Utility method for displaying nice reset reason from a SYS_RESET_IND message.

Parameters:
reason the reset reason
Returns:
a string containing the name of the reset reason.
unsigned char* getVersion (  ) 

Retrieves the ZNP's version information using SYS_VERSION command.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
See also:
Interface Specification for order of fields
void printZnpBuf (  ) 

Displays the contents of the Znp Buffer, znpBuf. Useful for debugging ZNP communications.

unsigned char* readNvItem ( unsigned char  nvItem  ) 

Retrieves the specified Non-Volatile (NV) memory item from the ZNP.

Precondition:
ZNP was initialized.
Parameters:
nvItem which nvItem to write, 1 through 6 inclusive
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the NV item retrieved, or a pointer to indeterminate data if error.
Note:
does not verify the length of the returned nvItem was what we expected
void setCallbacks ( unsigned char  cb  ) 

Enable/Disabless callbacks on the ZNP.

Parameters:
cb must be either CALLBACKS_ENABLED or CALLBACKS_DISABLED
See also:
section ZCD_NV_ZDO_DIRECT_CB in ZNP Interface Specification
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setChannel ( unsigned long  channelMask  ) 

Configures the ZNP to only join a network according to the given channel mask.

Parameters:
channelMask bitmap of which channels to use. If channelMask = ANY_CHANNEL then the radio will join a network on any channel. Default channel after a CLEAR_CONFIG is channel 11, or (MSB first) 0x00000800.
Note:
: if using a packet sniffer, be sure to change the channel on the packet sniffer too or else you won't see any packets.
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setPanId ( unsigned int  panId  ) 

Configures the ZNP to only join a network with the given panId. If panId = ANY_PAN then the radio will join any network.

Parameters:
panId the PANID to join, or ANY_PAN to join any PAN
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setPollRate ( unsigned int  pollRate  ) 

Sets the ZCD_NV_POLL_RATE, which is used by end devices and controls how often an end device polls its associated router for new data. Default is 2000 (2 seconds). Higher numbers will increase latency but reduce average power consumption.

Parameters:
rate how often (in mSec) to poll; must be between 1 to 65000, inclusive.
See also:
section ZCD_NV_POLL_RATE in ZNP Interface Specification
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setSecurityKey ( unsigned char *  key  ) 

Loads the specified key into the ZNP. Does not change security mode, need to use setSecurityMode() too.

Note:
if NOT using pre-configured keys then the coordinator will distribute its key to all devices.
Parameters:
key preConfiguredKey a 16B key to use
Precondition:
setSecurityMode() called
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setSecurityMode ( unsigned char  securityMode  ) 

Configures the ZNP for the specified security mode. If securityMode = SECURITY_MODE_OFF then only ZCD_NV_SECURITY_MODE is written. Otherwise ZCD_NV_SECURITY_MODE and ZCD_NV_PRECFGKEYS_ENABLE are written.

Note:
if NOT using pre-configured keys then the coordinator will distribute its key to all devices.
Parameters:
securityMode SECURITY_MODE_OFF or SECURITY_MODE_PRECONFIGURED_KEYS or SECURITY_MODE_COORD_DIST_KEYS
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
void setStartupOptions ( unsigned char  option  ) 

Configures startup options on the ZNP. These will reset various parameters back to their factory defaults. The radio supports two types of clearing state, and both are supported:

  • STARTOPT_CLEAR_CONFIG restores all settings to factory defaults. Must restart the ZNP after using this option.
  • STARTOPT_CLEAR_STATE only clears network settings (PAN ID, channel, etc.)
    Note:
    all ZB_WRITE_CONFIGURATION commands take approx. 3.5mSec between SREQ & SRSP; presumably to write to flash inside the CC2530ZNP.
    Parameters:
    option which options to set. Must be zero, STARTOPT_CLEAR_CONFIG, or STARTOPT_CLEAR_STATE.
    Postcondition:
    znpResult contains the error code, or ZNP_SUCCESS if success.
void setZigbeeDeviceType ( unsigned char  deviceType  ) 

Sets the Zigbee Device Type for the ZNP.

Parameters:
deviceType the type of Zigbee device. Must be COORDINATOR, ROUTER, or END_DEVICE
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
unsigned char sysGpio ( unsigned char  operation,
unsigned char  value 
)

Performs the specified General Purpose Input/Output (GPIO) operation.

Parameters:
operation which GPIO operation to do: GPIO_SET_DIRECTION, GPIO_SET_INPUT_MODE, GPIO_SET, GPIO_CLEAR, GPIO_TOGGLE, GPIO_READ
value the value to write
Returns:
the value returned by the ZNP if operation = GPIO_READ; indeterminate value otherwise
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
signed int waitForMessage ( unsigned int  messageType,
unsigned char  timeoutSecs 
)

Waits for the specified type of message. Silently discards any other messages received. Received message will be in znpBuf[]. If the specified type of message isn't received then returns error code.

Returns:
0 if success, -21 if timeout, -31 if received a message but it wasn't the type we're expecting.
void writeNvItem ( unsigned char  nvItem,
unsigned char *  data 
)

Writes the specified Non-Volatile (NV) memory item to the ZNP. The contents of the selected nvItem will be overwritten from memory starting at data.

Precondition:
ZNP was initialized.
Parameters:
nvItem which nvItem to write, 1 through 6 inclusive
data the data to write
Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
unsigned char* znpInit (  ) 

Initializes the hardware interface to the ZNP (SPI). This method must be called before any other method in the library.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
See also:
Interface Specification for order of fields
Todo:
modify this if using UART
unsigned char* znpReset (  ) 

Resets the ZNP using hardware and retrieves the SYS_RESET_IND message. This method is used to restart the ZNP's internal state machine and apply changes to startup options, zigbee device type, etc.

Postcondition:
znpResult contains the error code, or ZNP_SUCCESS if success.
Returns:
a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
See also:
Interface Specification for order of fields
 All Data Structures Files Functions Variables Defines
Generated on Thu Aug 19 11:47:25 2010 for Zigbee Network Processor Library by  doxygen 1.6.3